FastAPI-tiedostojen latauksen hallinta: Syväsukellus Multipart-lomakkeiden käsittelyyn

Nykyaikaisissa verkkosovelluksissa kyky käsitellä tiedostolatauksia on olennainen vaatimus. Olipa kyseessä käyttäjien profiilikuvien, käsiteltävien asiakirjojen tai jaettavan median lähettäminen, vankat ja tehokkaat tiedostolatausmekanismit ovat ratkaisevan tärkeitä. FastAPI, suorituskykyinen Python-web-kehys, on erinomainen tällä alueella tarjoten virtaviivaisen tavan hallita multipart-lomakedataa, joka on standardi tiedostojen lähettämiseen HTTP:n kautta. Tämä kattava opas opastaa sinut FastAPI-tiedostolatausten monimutkaisuuksien läpi perus toteutuksesta edistyneisiin näkökohtiin, varmistaen, että voit luottavaisin mielin rakentaa tehokkaita ja skaalautuvia API:ja maailmanlaajuiselle yleisölle.

Multipart-lomakedatan ymmärtäminen

Ennen kuin sukellamme FastAPI:n toteutukseen, on olennaista ymmärtää, mitä multipart-lomakedata on. Kun selain lähettää lomakkeen, joka sisältää tiedostoja, se käyttää tyypillisesti enctype="multipart/form-data" -attribuuttia. Tämä koodaustyyppi jakaa lomakkeen lähetyksen useisiin osiin, joista jokaisella on oma sisältötyyppinsä ja disposition tiedot. Tämä mahdollistaa erityyppisten tietojen lähettämisen yhdessä HTTP-pyynnössä, mukaan lukien tekstikentät, ei-tekstikentät ja binääritiedostot.

Jokainen multipart-pyynnön osa koostuu:

• Content-Disposition Header: Määrittää lomakekentän nimen (name) ja tiedostojen osalta alkuperäisen tiedostonimen (filename).
• Content-Type Header: Ilmaisee osan MIME-tyypin (esim. text/plain, image/jpeg).
• Body: Kyseisen osan varsinainen data.

FastAPI:n lähestymistapa tiedostolatauksiin

FastAPI hyödyntää Pythonin standardikirjastoa ja integroituu saumattomasti Pydanticin kanssa datan validointia varten. Tiedostolatauksia varten se käyttää UploadFile-tyyppiä fastapi-moduulista. Tämä luokka tarjoaa kätevän ja turvallisen käyttöliittymän ladattujen tiedostojen datan käyttämiseen.

Tiedostolatauksen perus toteutus

Aloitetaan yksinkertaisella esimerkillä siitä, miten luodaan FastAPI:ssa päätepiste, joka hyväksyy yhden tiedoston latauksen. Käytämme File-funktiota fastapi:sta tiedostoparametrin määrittämiseen.

            from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/files/")
async def create_file(file: UploadFile):
    return {"filename": file.filename, "content_type": file.content_type}

            

              
                Copy
              
            
          

Tässä esimerkissä:

• Tuomme FastAPI:n, File:n ja UploadFile:n.
• Päätepiste /files/ on määritetty POST-pyynnöksi.
• Parametri file on annotoitu UploadFile:lla, mikä merkitsee, että se odottaa tiedoston latausta.
• Päätepistefunktion sisällä voimme käyttää ladatun tiedoston ominaisuuksia, kuten filename ja content_type.

Kun asiakas lähettää POST-pyynnön /files/-osoitteeseen liitetiedoston kanssa (tyypillisesti lomakkeen kautta, jossa on enctype="multipart/form-data"), FastAPI käsittelee automaattisesti jäsentämisen ja tarjoaa UploadFile-objektin. Voit sitten olla vuorovaikutuksessa tämän objektin kanssa.

Ladattujen tiedostojen tallentaminen

Usein sinun on tallennettava ladattu tiedosto levylle tai käsiteltävä sen sisältö. UploadFile-objekti tarjoaa menetelmiä tähän:

• read(): Lukee koko tiedoston sisällön muistiin tavuina. Käytä tätä pienemmille tiedostoille.
• write(content: bytes): Kirjoittaa tavuja tiedostoon.
• seek(offset: int): Muuttaa tiedoston nykyistä sijaintia.
• close(): Sulkee tiedoston.

On tärkeää käsitellä tiedostotoimintoja asynkronisesti, erityisesti kun käsitellään suuria tiedostoja tai I/O-sidonnaisia tehtäviä. FastAPI:n UploadFile tukee asynkronisia toimintoja.

            from fastapi import FastAPI, File, UploadFile
import shutil

app = FastAPI()

@app.post("/files/save/")
async def save_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
    return {"info": f"file '{file.filename}' saved at '{file_location}'"}

            

              
                Copy
              
            
          

Tässä parannetussa esimerkissä:

• Käytämme File(...) osoittamaan, että tämä parametri on pakollinen.
• Määritämme paikallisen polun, johon tiedosto tallennetaan. Varmista, että uploads-hakemisto on olemassa.
• Avaamme kohdetiedoston binäärikirjoitustilassa (`"wb+"`).
• Luemme asynkronisesti ladatun tiedoston sisällön käyttämällä await file.read() ja kirjoitamme sen sitten paikalliseen tiedostoon.

Huomaa: Koko tiedoston lukeminen muistiin komennolla await file.read() voi olla ongelmallista erittäin suurille tiedostoille. Harkitse tällaisissa tapauksissa tiedoston sisällön suoratoistoa.

Tiedoston sisällön suoratoisto

Suurille tiedostoille koko sisällön lukeminen muistiin voi johtaa liialliseen muistin kulutukseen ja mahdollisiin muistivirheisiin. Muistitehokkaampi lähestymistapa on suoratoistaa tiedosto pala palalta. shutil.copyfileobj-funktio on erinomainen tähän, mutta meidän on mukautettava se asynkronisiin toimintoihin.

            from fastapi import FastAPI, File, UploadFile
import aiofiles # Install using: pip install aiofiles

app = FastAPI()

@app.post("/files/stream/")
async def stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        content = await file.read()
        await out_file.write(content)
    return {"info": f"file '{file.filename}' streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

aiofiles:in avulla voimme tehokkaasti suoratoistaa ladatun tiedoston sisällön kohdetiedostoon lataamatta koko tiedostoa muistiin kerralla. await file.read() tässä kontekstissa lukee edelleen koko tiedoston, mutta aiofiles käsittelee kirjoittamisen tehokkaammin. Todellista pala palalta -suoratoistoa varten UploadFile:n avulla iteroidaan tyypillisesti await file.read(chunk_size):n yli, mutta aiofiles.open ja await out_file.write(content) on yleinen ja tehokas malli tallentamiseen.

Selkeämpi suoratoistotapa käyttämällä lohkomista:

            from fastapi import FastAPI, File, UploadFile
import aiofiles

app = FastAPI()

CHUNK_SIZE = 1024 * 1024 # 1MB chunk size

@app.post("/files/chunked_stream/")
async def chunked_stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        while content := await file.read(CHUNK_SIZE):
            await out_file.write(content)
    return {"info": f"file '{file.filename}' chunked streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

Tämä `chunked_stream_file`-päätepiste lukee tiedoston 1 Mt:n lohkoina ja kirjoittaa jokaisen lohkon tulostiedostoon. Tämä on muistitehokkain tapa käsitellä mahdollisesti erittäin suuria tiedostoja.

Useiden tiedostojen latauksen käsittely

Verkkosovellukset vaativat usein, että käyttäjät lataavat useita tiedostoja samanaikaisesti. FastAPI tekee tästä yksinkertaista.

Tiedostoluettelon lataaminen

Voit hyväksyä tiedostoluettelon annotoimalla parametrisi UploadFile-luettelolla.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/multiple/")
async def create_multiple_files(
    files: List[UploadFile] = File(...)
):
    results = []
    for file in files:
        # Process each file, e.g., save it
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {"files_processed": results}

            

              
                Copy
              
            
          

Tässä skenaariossa asiakkaan on lähetettävä useita osia samalla lomakekentän nimellä (esim. `files`). FastAPI kerää ne Python-luetteloksi, joka sisältää UploadFile-objekteja.

Tiedostojen ja muiden lomaketietojen yhdistäminen

On tavallista, että lomakkeet sisältävät sekä tiedostokenttiä että tavallisia tekstikenttiä. FastAPI käsittelee tämän sallimalla muiden parametrien määrittämisen käyttämällä tavallisia tyyppiannotaatioita sekä Form-lomakekentille, jotka eivät ole tiedostoja.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/mixed/")
async def upload_mixed_data(
    description: str = Form(...),
    files: List[UploadFile] = File(...) # Accepts multiple files with the name 'files'
):
    results = []
    for file in files:
        # Process each file
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {
        "description": description,
        "files_processed": results
    }

            

              
                Copy
              
            
          

Kun käytät työkaluja, kuten Swagger UI tai Postman, määrität description-kentän tavalliseksi lomakekentäksi ja lisäät sitten useita osia files-kenttään, joista jokaisen sisältötyyppi on asetettu asianmukaiseksi kuva-/asiakirjatyypiksi.

Edistyneet ominaisuudet ja parhaat käytännöt

Perustiedostojen käsittelyn lisäksi useat edistyneet ominaisuudet ja parhaat käytännöt ovat ratkaisevan tärkeitä vankkojen tiedostolataus-API:en rakentamisessa.

Tiedostokoon rajoitukset

Rajoittamattomien tiedostolatausten salliminen voi johtaa palvelunestohyökkäyksiin tai liialliseen resurssien kulutukseen. Vaikka FastAPI itse ei oletusarvoisesti pakota tiukkoja rajoituksia kehyksen tasolla, sinun on toteutettava tarkastuksia:

• Sovellustasolla: Tarkista tiedostokoko sen vastaanottamisen jälkeen, mutta ennen käsittelyä tai tallentamista.
• Web-palvelin-/välityspalvelintasolla: Määritä web-palvelimesi (esim. Nginx, Uvicorn työntekijöiden kanssa) hylkäämään pyynnöt, jotka ylittävät tietyn hyötykuorman koon.

Esimerkki sovellustason kokotarkistuksesta:

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

MAX_FILE_SIZE_MB = 10
MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024

@app.post("/files/limited_size/")
async def upload_with_size_limit(file: UploadFile = File(...)):
    if len(await file.read()) > MAX_FILE_SIZE_BYTES:
        raise HTTPException(status_code=400, detail=f"File is too large. Maximum size is {MAX_FILE_SIZE_MB}MB.")
    
    # Reset file pointer to read content again
    await file.seek(0)
    
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully."}

            

              
                Copy
              
            
          

Tärkeää: Kun olet lukenut tiedoston tarkistaaksesi sen koon, sinun on käytettävä komentoa await file.seek(0) nollataksesi tiedostokohdistin alkuun, jos aiot lukea sen sisällön uudelleen (esim. tallentaaksesi sen).

Sallitut tiedostotyypit (MIME-tyypit)

Latausten rajoittaminen tiettyihin tiedostotyyppeihin parantaa turvallisuutta ja varmistaa datan eheyden. Voit tarkistaa UploadFile-objektin content_type-attribuutin.

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

ALLOWED_FILE_TYPES = {"image/jpeg", "image/png", "application/pdf"}

@app.post("/files/restricted_types/")
async def upload_restricted_types(file: UploadFile = File(...)):
    if file.content_type not in ALLOWED_FILE_TYPES:
        raise HTTPException(status_code=400, detail=f"Unsupported file type: {file.content_type}. Allowed types are: {', '.join(ALLOWED_FILE_TYPES)}")
        
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully and is of an allowed type."}

            

              
                Copy
              
            
          

Vankempaa tyypin tarkistusta varten, erityisesti kuvien osalta, kannattaa harkita kirjastojen, kuten Pillow, käyttöä tiedoston todellisen sisällön tarkastamiseen, koska MIME-tyyppejä voidaan joskus väärentää.

Virheiden käsittely ja käyttäjäpalaute

Anna käyttäjälle selkeitä ja toteuttamiskelpoisia virheilmoituksia. Käytä FastAPI:n HTTPException-poikkeusta vakiomuotoisia HTTP-virhevastauksia varten.

• Tiedostoa ei löydy/puuttuu: Jos vaadittavaa tiedostoparametria ei lähetetä.
• Tiedostokoko ylitetty: Kuten kokorajoitusesimerkissä on esitetty.
• Virheellinen tiedostotyyppi: Kuten tyyppirajoitusesimerkissä on esitetty.
• Palvelinvirheet: Tiedostojen tallennuksen tai käsittelyn aikana ilmenevät ongelmat (esim. levy täynnä, käyttöoikeusvirheet).

Turvallisuusnäkökohdat

Tiedostolataukset aiheuttavat turvallisuusriskejä:

• Haitalliset tiedostot: Suoritettavien tiedostojen (.exe, .sh) tai muiden tiedostotyyppien peitteeksi naamioitujen komentosarjojen lataaminen. Varmista aina tiedostotyypit ja harkitse ladattujen tiedostojen tarkistamista haittaohjelmien varalta.
• Polun läpikäynti: Puhdista tiedostonimet estääksesi hyökkääjiä lataamasta tiedostoja luvattomiin hakemistoihin (esim. käyttämällä tiedostonimiä, kuten ../../etc/passwd). FastAPI:n UploadFile käsittelee tiedostonimien peruspuhdistuksen, mutta lisävarovaisuus on viisasta.
• Palvelunestohyökkäys: Ota käyttöön tiedostokoon rajoitukset ja mahdollisesti nopeuden rajoittaminen latauspäätepisteissä.
• Cross-Site Scripting (XSS): Jos näytät tiedostonimiä tai tiedostojen sisältöä suoraan verkkosivulla, varmista, että ne on oikein poistettu XSS-hyökkäysten estämiseksi.

Paras käytäntö: Tallenna ladatut tiedostot web-palvelimesi dokumenttikansion ulkopuolelle ja tarjoile ne erillisen päätepisteen kautta asianmukaisilla käyttöoikeuksien hallinnoilla tai käytä sisällönjakeluverkkoa (CDN).

Pydantic-mallien käyttäminen tiedostolatausten kanssa

            from fastapi import FastAPI, File, UploadFile, Form
from pydantic import BaseModel
from typing import Optional

class UploadMetadata(BaseModel):
    title: str
    description: Optional[str] = None

app = FastAPI()

@app.post("/files/model_metadata/")
async def upload_with_metadata(
    metadata: str = Form(...), # Receive metadata as a JSON string
    file: UploadFile = File(...)
):
    import json
    try:
        metadata_obj = UploadMetadata(**json.loads(metadata))
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON format for metadata")
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Error parsing metadata: {e}")

    # Now you have metadata_obj and file
    # Proceed with saving file and using metadata
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())

    return {
        "message": "File uploaded successfully with metadata",
        "metadata": metadata_obj,
        "filename": file.filename
    }

            

              
                Copy
              
            
          

Suuret tiedostolataukset ja lohkominen

Hyvin suurille tiedostoille (esim. gigatavuja) jopa suoratoisto voi osua web-palvelimen tai asiakaspuolen rajoituksiin. Edistyneempi tekniikka on lohkotut lataukset, jossa asiakas jakaa tiedoston pienempiin osiin ja lataa ne peräkkäin tai rinnakkain. Palvelin kokoaa sitten nämä lohkot uudelleen. Tämä edellyttää tyypillisesti mukautettua asiakaspuolen logiikkaa ja palvelinpäätepistettä, joka on suunniteltu käsittelemään lohkojen hallintaa (esim. lohkojen tunnistaminen, väliaikainen tallennustila ja lopullinen kokoaminen).

Vaikka FastAPI ei tarjoa sisäänrakennettua tukea asiakkaan käynnistämille lohkotuille latauksille, voit toteuttaa tämän logiikan FastAPI-päätepisteissäsi. Tämä edellyttää sellaisten päätepisteiden luomista, jotka:

• Vastaanottavat yksittäisiä tiedostolohkoja.
• Talloavat nämä lohkot väliaikaisesti, mahdollisesti metadatan kanssa, joka osoittaa niiden järjestyksen ja lohkojen kokonaismäärän.
• Tarjoavat päätepisteen tai mekanismin, joka ilmoittaa, milloin kaikki lohkot on ladattu, mikä käynnistää uudelleenkokoamisprosessin.

Tämä on monimutkaisempi tehtävä ja edellyttää usein JavaScript-kirjastoja asiakaspuolella.

Kansainvälistymis- ja globalisaationäkökohdat

Kun rakennetaan API:ja maailmanlaajuiselle yleisölle, tiedostolataukset vaativat erityistä huomiota:

• Tiedostonimet: Käyttäjät ympäri maailmaa voivat käyttää muita kuin ASCII-merkkejä tiedostonimissä (esim. aksenttimerkkejä, ideogrammeja). Varmista, että järjestelmäsi käsittelee ja tallentaa nämä tiedostonimet oikein. UTF-8-koodaus on yleensä standardi, mutta syvä yhteensopivuus voi edellyttää huolellista koodausta/dekoodausta ja puhdistusta.
• Tiedostokoon yksiköt: Vaikka Mt ja Gt ovat yleisiä, ole tietoinen siitä, miten käyttäjät havaitsevat tiedostokoot. Rajojen näyttäminen käyttäjäystävällisellä tavalla on tärkeää.
• Sisältötyypit: Käyttäjät voivat ladata tiedostoja, joilla on harvinaisempia MIME-tyyppejä. Varmista, että sallittujen tyyppien luettelosi on kattava tai riittävän joustava käyttötarkoitustasi varten.
• Alueelliset määräykset: Ole tietoinen tiedonsiirtolakeista ja -määräyksistä eri maissa. Ladattujen tiedostojen tallentaminen voi edellyttää näiden sääntöjen noudattamista.
• Käyttöliittymä: Tiedostojen latauksen asiakaspuolen käyttöliittymän tulisi olla intuitiivinen ja tukea käyttäjän kieltä ja aluetta.

Työkalut ja kirjastot testausta varten

• Swagger UI (Interactive API Docs): FastAPI luo automaattisesti Swagger UI -dokumentaation. Voit testata tiedostolatauksia suoraan selainliittymästä. Etsi tiedoston syöttökenttä ja napsauta "Choose File" -painiketta.
• Postman: Suosittu API-kehitys- ja testaustyökalu. Tiedostolatauspyynnön lähettämiseksi:
• Aseta pyyntömenetelmäksi POST.
• Kirjoita API-päätepisteen URL-osoite.
• Siirry "Body"-välilehdelle.
• Valitse tyypiksi "form-data".
• Kirjoita avain-arvo-pareihin tiedostoparametrisi nimi (esim. file).
• Vaihda tyyppi "Text"-kohdasta "File"-kohtaan.
• Napsauta "Choose Files" valitaksesi tiedoston paikallisesta järjestelmästäsi.
• Jos sinulla on muita lomakekenttiä, lisää ne samalla tavalla pitäen niiden tyyppinä "Text".
• Lähetä pyyntö.
• cURL: Komentorivityökalu HTTP-pyyntöjen tekemiseen.
• Yhdelle tiedostolle: curl -X POST -F "file=@/path/to/your/local/file.txt" http://localhost:8000/files/
• Useille tiedostoille: curl -X POST -F "files=@/path/to/file1.txt" -F "files=@/path/to/file2.png" http://localhost:8000/files/multiple/
• Sekalaiselle datalle: curl -X POST -F "description=My description" -F "files=@/path/to/file.txt" http://localhost:8000/files/mixed/
• Pythonin `requests`-kirjasto: Ohjelmalliseen testaamiseen.

            import requests

url = "http://localhost:8000/files/save/"
files = {'file': open('/path/to/your/local/file.txt', 'rb')}

response = requests.post(url, files=files)
print(response.json())

# For multiple files
url_multiple = "http://localhost:8000/files/multiple/"
files_multiple = {
    'files': [('file1.txt', open('/path/to/file1.txt', 'rb')),
              ('image.png', open('/path/to/image.png', 'rb'))]
}
response_multiple = requests.post(url_multiple, files=files_multiple)
print(response_multiple.json())

# For mixed data
url_mixed = "http://localhost:8000/files/mixed/"
data = {'description': 'Test description'}
files_mixed = {'files': open('/path/to/another_file.txt', 'rb')}
response_mixed = requests.post(url_mixed, data=data, files=files_mixed)
print(response_mixed.json())

            

              
                Copy
              
            
          

Johtopäätös

FastAPI tarjoaa tehokkaan, tehokkaan ja intuitiivisen tavan käsitellä multipart-tiedostolatauksia. Hyödyntämällä UploadFile-tyyppiä ja asynkronista ohjelmointia kehittäjät voivat rakentaa vankkoja API:ja, jotka integroivat saumattomasti tiedostojen käsittelyominaisuudet. Muista priorisoida tietoturva, toteuttaa asianmukainen virheiden käsittely ja ottaa huomioon maailmanlaajuisen käyttäjäkunnan tarpeet käsittelemällä näkökohtia, kuten tiedostonimien koodausta ja määräystenmukaisuutta.

Olitpa rakentamassa yksinkertaista kuvienjakopalvelua tai monimutkaista asiakirjojen käsittelyalustaa, FastAPI:n tiedostolatausominaisuuksien hallitseminen on merkittävä voimavara. Jatka sen ominaisuuksien tutkimista, toteuta parhaita käytäntöjä ja tarjoa poikkeuksellisia käyttökokemuksia kansainväliselle yleisöllesi.